API 토큰은 애플리케이션(또는 사용자)이 API에 접근할 때 자신을 증명하고 권한을 부여받기 위해 사용하는 고유한 문자열 형태의 자격 증명입니다. 간단히 말해 “누가 요청을 하는지”와 “무엇을 할 수 있는지”를 API 서버가 확인하도록 돕는 열쇠 역할을 합니다. 주요 특징 및 종류 - API 키: 보통 고정된 문자열. 간단한 인증에 사용되지만 권한·만료 관리가 약함. - 베어러 토큰(Bearer token): HTTP Authorization 헤더에 포함되어 전달되는 경우가 많음. OAuth 2.0 액세스 토큰이 대표적. - JWT(JSON Web Token): 서명된 토큰으로 발행자, 대상(audience), 만료(exp) 등의 클레임(정보)을 포함할 수 있어 자체 검증이 가능. - 불투명 토큰(opaque token): 서버에서만 의미를 아는 랜덤 문자열으로, 서버가 별도 저장소에서 확인함. 사용 방식(예) - HTTP 헤더: Authorization: Bearer <토큰> - 커스텀 헤더: X-API-Key: <토큰> - 쿼리 파라미터: ?api_key=<토큰> (권장하지 않음 — 로그나 브라우저 기록에 남을 수 있음) 보안 및 운영 모범 사례 - TLS(HTTPS)를 항상 사용해 전송 중 탈취를 방지. - 최소 권한 원칙: 토큰에 필요한 권한(scope)을 최소화. - 만료 시간을 설정하고 단기 토큰 + 리프레시 토큰 구조 사용 권장. - 토큰 회전(rotation)과 주기적 갱신, 유출 시 즉시 폐기(리보크) 기능 마련. - 안전한 저장: 서버 환경변수나 시크릿 매니저에 보관하고, 클라이언트 코드나 공개 리포지터리에 포함시키지 않음. - 로깅 시 토큰 값은 마스킹하거나 기록하지 않음. - 발급·검증 시 발급자(issuer), 대상(audience), 서명(또는 저장소 조회), 만료 여부 등을 확인. - IP 화이트리스트, 사용량 제한(rate limiting), 동시성 제한 등 추가 보호 적용 가능. 토큰 선택 기준 - 단순 서비스나 내부 시스템에는 API 키로 충분할 수 있음. - 외부 사용자 인증, 권한 위임, 만료·갱신 관리가 필요하면 OAuth 액세스 토큰·리프레시 토큰 또는 JWT 사용을 권장. 요약하자면, API 토큰은 API 요청자의 신원과 권한을 확인하는 데 쓰이는 비밀 문자열이며, 안전한 전송·저장·관리가 핵심입니다.
